Magic Words IE (Import/Export) 1.1
by Amaikokonut with Bonus Creature "Path Pain" contributed by Mea (see notes at the end for info)


May be found at Naturing :: Nurturing (https://naturingnurturing.blogspot.com) and/or Naturing :: Nurturing :: Static (https://naturingnurturing.songua.com) and/or a friendly community archive near you! It's also possible this update got finished in time for CCSF '23, in which case, happy CCSF!


If you're going to rehost or redistribute this agent, please leave this readme intact.


If you have any comments, questions, bug reports, or just want to chat, email amaikokonut@songua.com


:: Installation ::

BE SURE TO REMOVE PREVIOUS VERSIONS OF THIS AGENT BEFORE INSTALLATION!

This Magic Words agent requires Magic Words Core 1.3 to function fully. 1.1 will not work, and 1.2 will only let you inject agents at the hand. For your convenience, a zip file file containing Magic Words 1.3 is included in this file, but you can ignore it if you already have it (or a newer version of Magic Words) installed. A copy of the Speech Bubble Upgrades 1.2 is also included, and is required for other agents (such as the keyboard handler and the Speech Repeater gadget) to be able to use this Magic Words function.

This zip contains both an agent and a cosfile. If you rarely use this set of Magic Words frequently, you can move the .agents file to your My Agents folder and inject it by hand on a per-world basis. If you use it a lot, place the .cos file in a subfolder in your Bootstrap so it will be installed into every world. \Bootstrap\010 Docking Station is okay, but keeping all your Magic Words cosfiles in their own bootstrap folder, such as \021 Magic Words, will make it easier if you need to find them later.


:: About ::

First, a word of caution-- the more creatures you have in your My Creatures folder, the slower these commands will run. If you have hundreds of creatures, you may occasionally get the 'infinite loop' error, but it's not actually infinite-- you can retry until the script finishes running, or abort the loop and run the command again until you get all the creatures you want. Additionally, be very careful when importing tons of creatures. The last thing you want is to import 500 creatures and then your game crashes, erasing all the creatures you just imported.

The basic syntax for these commands is simply Import [what] and Export [what]. There can be many 'whats'. You can specify number, species, gender, lifestage, and/or world, in any order. There is a safeguard limit of 50 creatures for imports, but you can override this (at your own risk!) by specifying a number higher than 50 or simply "all" Some examples:

Import 4 -> Imports 4 of any creature
Import ettin -> Imports one ettin
Import norns -> Imports up to 50 norns
Export male norns -> Exports all male norns
Import all grendels -> Imports ALL grendels, even if there are more than 50 in your exports folder.
Import ettin 4 -> Imports 4 ettins. 'Import ettins 4' has the same effect.
Import 4 ettin child female -> Imports 4 female child ettins
Export youths -> Exports all youth creatures
Import 10 adult genderless -> Imports 10 adult genderless creatures of any species
Import 4 ettin child female w:ettin_world -> Imports 4 female child ettins that were exported from a world named "Ettin World"

'World' is a special parameter that will look for only creatures who have been exported from the specified world. This is useful when doing a complete migration from another world. This specification must begin with "w:" and contain no spaces. If there are spaces in the world name, you will need to replace them with underscores. This does mean that there is no distinction between creatures exported from 'Albian Reborn' and 'albia_reborn' so if for some reason you name your worlds like that, keep that in mind.

The export command works identically to the import, sans the world parameter and 50 creature limit.

One last thing worth mentioning-- this agent does include an additional command: 'Cloning Toggle'. By default, it is set to NOT bypass import cloning and WILL clone creatures that you import that were not originally exported from one of your worlds (such as creatures you've downloaded). This is important to prevent moniker clashes if the creature is sent through the warp later. If you choose to turn cloning off, PLEASE do not send any of your creatures though Natsue or any other babel-clone warp implementation. While this may not appear to impact anything on your end, it messes up the warp server's creature history, so please be polite and don't do this. Also note that this toggle ONLY affects Magic Words Import, and does not impact imports that happen via the traditional control panel.

Otherwise, hope you find this useful!

:: Bonus ::

Included is a creature very appropriately autonamed Path Pain, with a moniker, also appropriately, ending in 666. While rigorously testing Magic Words IE, Mea discovered that this creature-- and for some reason, this creature only-- was causing the agent to throw errors after she had moved it out of the exports folder. When she sent me the creature, I discovered the exact same thing. It was super ominous. Eventually we were able to fix the error with a better-placed PRAY REFR, but this creature might actually be cursed, so in the true spirit of 2020 (the original release year for this agent), we're passing this curse on to you. Import at your own risk, of course! And like any creature you download from the internet, you'll need to bypass import cloning to retain the original name and moniker of the creature.

:: Additional Credits ::

Special thanks to Mea, for requesting this in the first place, even though I got way out of control implementing it.

EXTRA special thanks to Mea, AGAIN, for testing the HECK out of this and finding numerous bugs and quirks leading to a much more easily understandable implementation of this system overall.

:: Changelog ::

08-18-2023: Added support for speech-bubble-calling agents (requires speech bubble upgrades 1.2 or higher and magic words core 1.3)
12-24-2020: Inital Commitment to Eventual Release (??)
